Gigarom 1/Gigarom Macintosh Archives (Quantum Leap)(CDRM1080320)(1993).iso/FILES/DEV/A-B/Alpha.5.05.cpt/Help/Tickle

Text File | 1992-08-31 | 35KB | 816 lines

                    tickle
           Assembled and Written By
                  Tim Endres

                April 2, 1992
                Release 3.1v4

         Internet:         [e-mail]
         UUCP:          heifetz!tbomb!time
         AppleLink:   [e-mail]@INTERNET#
         CompuServe:  >INTERNET:[e-mail]


This software is the result of a network programming community propelled
by software sharing, allowing work to be built upon others' work
eliminating redundancy and allowing continual incremental
enhancement.

Please give tickle to anyone you wish, but please give them the entire
package so that they have the documentation and references.

If you have any questions, suggestions, or just have some compelling need
to send email, please address it to [e-mail].


*** What is Tickle? ***

Tickle is a glom of items that were assembled over a long period of time.
Some was my own insanity and others came from the net. Finally, the nice
little tcl language came up at USENIX, several people moaned about
wanting it on the Mac, and it seemed reasonable.

You will find that tickle is an invaluable tool in dealing with the various
data formats flying around on USENET as well as for various Macintosh
file formats. You will find BinHex, MacBinary, Apple Single/Double, Tar,
Compress, uuencode, and several TEXT file conversion utilities.

The added bonus of tcl allows for the automation of some of your tasks, as
the tcl language has been extended to support the file utilities of the
application, as well as allowing for further extensions by the user via
external commands ala HyperCard XCMDs. Support of HyperCard XCMDs
is being investigated for a future release.


*** What is TCL? ***

You should refer to the various included man pages and papers submitted
to USENIX for details about tcl. Briefly, tcl is a simple string based
scripting language designed to be included in standard applications. It will
allow you to perform many tasks that are otherwise very labor intensive.

TCL was created by a small set of very bright engineers, namely, John
Ousterhout and his graduate students. The Unix extensions were invented
and implemented by Karl Lehenbauer, Mark Diekhans and Peter da Silva
with help from Jordan Henderson. TCL was simply ported into tickle by
Tim Endres. Refer to the included documentation for further details.

Tickle comes with the libraries for the tcl interpreter included in tickle, so
that you may incorporate them into your work (assuming you have MPW).
Otherwise, you may retrieve the sources for the tcl interpreter from ICE.
The changes are significant, but based on release 4.0. Hopefully, we can
somehow get these modifications put into the general tcl release, but in the
meantime, people can use at least tcl. The release seems very stable.

To open a tcl script window, hold down the Shift key when you click on the
File menu, or when you use Cmd-N or Cmd-O. In script windows you can
execute any valid tcl code by selecting the text and pressing the Enter key (or
Apple-Return, or the yin-yang icon next to the horizontal scroll bar).

*** TCL Extensions ***

To make the tcl interpreter even more versatile, tickle gives you a text
window in which you can type tcl scripts, and execute tcl code by simply
selecting text and pressing the Enter key!! This will provide you with a very
powerful environment in which to experiment with tcl. You will find the
interface to be very much like MPW.

Further, the tcl language has been extended to allow you to write external
code resources (type 'XTCL') that are very similar in mechanism to
HyperCard's XCMDs. This will allow you to extend the tcl language
without dealing with the tcl sources, or rebuilding the tickle application.


*** Tickle TCL Interpreters ***

Anytime that you open a Text Window in tickle, you have instantiated a tcl
interpreter. You may treat the window as a text editor, or as a tcl shell. It
becomes a shell when you press the Enter key to execute the current line or
selection.

Each text window gets its own instantiation of a tcl interpreter. This means
that a command defined in one text window will not be available in another
text window's interpreter. This also means that a procedure may have two
different meanings in two different windows, without a conflict.

However, there are times when tickle needs to have a tcl interpreter
available, even if there is no text window open. For instance, if a DoScript
Apple Event comes into tickle, it will need an interpreter to execute the
script. To handle these situations, tickle creates a global interpreter. This
interpreter is created at startup of tickle, and lives until tickle is quit. The
global interpreter is where Apple Event scripts are executed, and where
Finder dropped tcl scripts are executed, and where the tickle CRON
expression is executed.

You may cause a text window to use the global interpreter, instead of a
private interpreter, by holding down the Shift key when opening the text
window. Text windows using the global interpreter will have the word
Global displayed in their lower left corner, instead of Local.

Also note that the script •tclinit will be executed within the context of the
global interpreter at tickle startup time. This provides an opportunity to
establish the global interpreter for commonly used extensions and for
CRON type tasks.
Specific TCL Extensions

The following commands have been added to the standard tcl command set
for the tickle application. The commands are mostly Macintosh specific.
Further, commands are provided to allow you to utilize the file utilities built
into tickle.

alertnote message_string
  This command will display message_string in a standard Macintosh alert box.

cd directory
  This command will set the current working directory to directory. The directory
  argument may or may not end with a colon. The working directory is the directory
  in which file names that contain no colons (folders) will be located with file related
  commands.

pwd
  This command will return the current working directory.

get_directory
  This command will display a standard Macintosh file dialog and request the user
  select a folder. The command will return the selected folder's full path name, or an
  empty string if the Cancel button was selected.

getenv varname
  This command will return the value of the environment variable varname.
  Environment variables are initialized by reading the file •tclenv. The environment
  file has the format varname=value as in the following example:

    TERM=vt100
    TCLINIT=::tcl:TclInit.tcl
    TCLDEFAULT=
    TEST=TEST
    TCLPATH=::tcl:tclsh:tclsrc

putenv varname value
  This command will set the environment variable varname to value.

cp fromName toName [force]
  This command will copy the file fromName and name the new file toName. If
  toName includes a path name that is different from the path in fromName, the copy
  will be made in a new directory (specified by toName). The copy can be made
  across volume (disk drives). The force option indicates that the copy should
  overwrite any existing file with the same name as toName. This command copies
  both data forks, and the Finder information.

mv fromName toName [force]
  This command will move the file fromName to toName. If toName includes a path
  name that is different from the path in fromName, the file will be moved into a new
  directory (specified by toName). The move can not be made across volume (disk
  drives). The force option indicates that the move should overwrite any existing file
  with the same name as toName.

rm fileName
  This command will delete the file fileName.

xtclcmd [-f filename] cmdname argument_list...
  This command will load the external command cmdname and pass it the argument
  list [ cmdname argument_list... ]. External command are code resources of type
  XTCL. They may be located in the resource fork of the tickle application, or they
  may be located in a file named XTCL File in the same directory as the tickle
  application. If the optional -f filename is included, the external command will first
  be loaded from filename before the other two files.
  See the appendix for a detailed description of the external tcl command interface.
  See the accompanying sources for an example of writing an XTCL.

askyesno prompt
  This command will display a Macintosh alert box with promptdisplayed with the
  push buttons Yes, No, Cancel.. The command will return the title of the button
  selected by the user.

getline prompt default
  This command will display a Macintosh alert box with promptdisplayed, a text edit
  field with default initially in the field, and with the push buttons OK, Cancel.. The
  command will return the text entered into the text edit field by the user, or an empty
  string if the user selected the Cancel button.

getfile prompt
  This command will display an SFGetFile() and return the full path name of the
  selected file, or an empty string if CANCEL button was selected.

putfile prompt original
  This command will display an SFPutFile() and return the full path name of the
  selected file, or an empty string if CANCEL button was selected. Original is the
  default name displayed for the user.

getfinfo fileName
  This command will display the standard Macintosh file information in the form:
  "'aeQL' 'QUIL' lvbsIdm 02/17/92 23:57:12 02/19/92 22:43:36 0,156 219 0".
  The fields are the fdCreator, fdType, fdFlags, flCreationDate, flCreationtime,
  flModDate, flModTime, fdLocation.H,V, dataForlLength, rsrcForkLength,
  respectively. The fdFlags field uses characters to represent bits:
    l/L    not locaked/Locked
    v/V    visible/notVisible
    b/B    not bundled/Bundled
    s/S    not system/System
    i/I    not initialized/Initialized
    d/D    not desktop/Desktop
    m/M    not sharable/sharable

setfinfo fileName [-a flags]
            [-c fdCreator] [-t fdTypes]
  This command will set the standard Macintosh file information. The flags setting
  must be of the same format as displayed by the getfinfo flag.

feedback string
  This command will display the string in the feedback window, as well as log the
  string if logging is turned on.

ctime time
  This command will return a UNIX time string of the format "Wed Feb 19
  22:43:36 1992". The parameter time is in Macintosh seconds, and would be the
  result of a now or file mtime command or the like.

now
  Returns the current time as Macintosh seconds. This is the number of seconds that
  have elapsed since Midnight Jan 1, 1904. Appropriate for input to ctime.

ticks
  Returns the current TickCount. Ticks are 60ths of a seconds. TickCount is the
  number of ticks since the Macintosh was started. The command:
        puts stdout [expr "[ticks] / 60"]
  will print the number of seconds since the Macintosh was booted.

mtime time ?long/short/abbrev?
  Returns a date and time string using the Macintosh International Utilities. The
  long/short/abbrev specification corresponds to the date. These are the following
  formats:
    short        3/16/92 9:20:46 PM
    abbrev    Mon, Mar 16, 1992 9:20:49 PM
    long        Monday, March 16, 1992 9:20:43 PM

listpick -p prompt list
  This command will display a dialog with the list displayed in a List Manager list. If
  the user presses the Cancel button, an empty string is returned. If the user selects
  the Open button, or double clicks an item in the list, that item will be returned.

glob

The original glob provided by the UNIX version of tcl was not quite adequate for
the more complex Macintosh file system. Issues such as invisible file handling,
Finder type and creator filtering, and space handling in file names. Release 6 of tcl
has dealt with the original problem with spaces in filenames, but the following
options are provided to deal with additional Macintosh issues.

Anyhow, the new glob now takes several options. They are:
    -i    This option causes glob to list invisible files also.
    -t TYPE    This option causes glob to only list file with the
        indicated Finder file typeTYPE. This option may be
        used with the -c option.
    -c CRTR    This option causes glob to only list file with the
        indicated Finder file creatorCRTR. This option may
        be used with the -t option.
        Also note that the original glob would skip dot files
        (i.e., file names the begin with a period)
        in the listing, unless the pattern began with a period.
        Tickle extends this concept one step further on the
        Macintosh, and skips spot files (i.e., file names that
        begin with '•'), unless the pattern starts with a spot.

yield_mac ?ticks? *** NOT YET INCORPORATED INTO ALPHA ***
  This will cause tcl to call WaitNextEvent, allowing other processes to run during
  CPU intensive tcl scripts, as well as allowing the user to switch application while a
  particularly long script is executing. The ticks argument determines the sleep_time
  ticks passed to WaitNextEvent() and as such determine the amount of sharing of the
  CPU that will be accomplished. Larger ticks values will slow down the tcl script
  allowing other programs more of the CPU. Smaller ticks values will speed up the
  tcl script at the expense other programs getting less of the CPU.

start_progress title start end pos msgexprc *** NOT YET INCORPORATED INTO ALPHA ***
  This will display a small window in which a sliding bar progress indicator will be
  displayed. The title will be the window title. Startand end are the end points of the
  progress indicator, and pos is the initial position of the indicator and must be
  between start and end. Msgexpr is a tickle expression that will be evaluated each
  time the position is updated by the update_progress function. The result of this
  expression will be displayed in the progress window as the progress message, and
  thus will most likely be the format command.

update_progress position *** NOT YET INCORPORATED INTO ALPHA ***
  This will update the progress indicator to show progress to position.

stop_progress *** NOT YET INCORPORATED INTO ALPHA ***
  This will close the progress indicator window.

logging on|off ?filename? *** NOT YET INCORPORATED INTO ALPHA ***
  This will turn the tickle logging on or off. If filename is provided with the on
  option, then the log file will be changed over to using the file named.

*** MORE EXTENSIONS ***

Many extensions to tickle were provided by Karl Lehenbauer and Mark Diekhans.
The most beneficial of those for tickle were included. These included math and
string functions, as well as a neat new loop command. The man pages are included
for some of these commands, but here is a brief summary.
There are math functions:
    acos    asin    atan    cos    sin    tan    cosh    sinh    tanh
    exp    log    log10    sqrt    fabs    floor    ceil    fmod    pow
The trig functions work with radians.
The function pi will simply return the constant.
The functions max and min will work on lists of floating point numbers.
The function random  limit will return a random number between + and - limit.
The function random seed [seedval] will set the seed for the random function to
seedval, or to the current time if seedval is not provided.

The function loop varname start end increment expr will increment the variable
varname from start to end by increment while executing expr for each increment.

*** Apple Event TCL Extensions *** NOT YET INCORPORATED INTO ALPHA ***

This implementation of tickle has extensive support for Apple Events. This
includes both support of the standard suite of events, as well as support for
script events, installing your own coercion and event handling routines, as
well as the ability to send Apple Events to other processes.

Tickle supports the 'misc' 'dosc' Apple Event, otherwise known as
DoScript.  Further, tickle supports both the typeChar and typeAlias forms of
input to the DoScript event. For the typeChar form, the text will be
considered a script and executed. For the typeAlias form, the file
represented by the alias will be executed. In either case, the result will be
returned via the reply as typeChar. The script will always be executed in
the context of the global interpreter.

Tickle also allows you to install Apple Event handlers via the aeload
command described below. This will install stand alone code modules to
handle Apple Events. The refCon to these handlers will point to a struct
that gives you the interpreter pointer to the global tcl interpreter, as well as
a procedure to make it easy for you to make calls back to the tcl interpreter
without linking in the tcl libraries in your handler. The aeload command
will also load coercion handlers. For more details on writing an Apple
Event handler or a coercion procedure, see the example sources included.

The loaded code resources are simply code resources with special names
that indicate their behavior. The first 4 characters (quartet ) of the name
determine the code type:

AEVT    Apple Event Handler.
CSPT    Pointer based coercion handler.
CSDS    AEDesc based coercion handler.

For AEVT resources, the second quartet of characters in the name
represent the event class and the third quartet of characters in the name
represent the event ID.

For CSPT and CSDS resources, the second quartet of characters in the
name represent the descriptor type of the incoming data (i.e., the from type)
and the third quartet of characters in the name represent the descriptor
type of the desired coercion (i.e., the to type).

Several commands have been added to the tcl language to facilitate the
sending of Apple Events to other hosts. They are itemized here:

aeopen name [ApplSig | port_name location_name]

This command creates a named connection with which you can send Apple Events
to other processes. If the ApplSig parameter is present, then the target will be the
local application with the specified four character signature.
If the port_name location_name parameters are given, they will define a process via
the PPCPortRec and LocationNameRec structures. The port_name paramater
should be in the form "name,type" and location_name should be in the form
object:type@zone. For instance, "tclEngine,tcl engine" "Joe's
Macintosh:PPCToolbox@myzone".
If no parameters are present, the command will display the PPCBrowser dialog
allowing you to select a process. Once this command is successfully executed, the
name may be used in any of the Apple Event commands listed below to identify the
targret of the Apple Event. There are a maximum of eight (8) targets that may be
open simultaneously.


aeclose name

This command will close the named Apple Event target opened by aeopen.


aesend name [-t ticks] [-w] [-i] [-o] [-l] [-x]
        class event data

This command is used to send an Apple Event to the named target, name,
previously opened by aeopen. Class and event are the corresponding four character
types that determine the class and event id of the Apple Event. The data field
contains the desired contents of the Apple Event.
The -t option allows the specification of the send timeout in ticks. The default is 120
or 2 seconds. The -w option uses the kAEWaitReply option, where kAENoReply is
the default. The -i option uses the kCanInteract option, where kAENeverInteract is
the default. The -o option allows you to select the standard output of the reply data.
This is only useful when talking with another tickle, since the standard output
paramater type is only defined by tickle. The -l option specifies that you want the
output in long format, with the returned data type (4 characters) first, then the data.
The -x option is used to get the output as hex data instead of text data. Regardless
of the data output format or options, the output will always be bracketed by curly
braces to avoid problems with spaces in the output.
The data field consists of pairs of parameters, the first being a flag and the second
data. The flag either begins with '+' or '-'. A '-' indicates that the two following
quartets of characters are the data key and type of the data that follows. For
example:
    -----TEXT "This is a string."
would create an Apple Event that contained a Direct Parameter (----) of type
'TEXT'. This is a perfectly good type for sending scripts, as in:
    aesend NAME misc dosc -----TEXT {print "Hello World!"}

The other form of data specification is the '+' form. This form uses the AEBuild
tool from Apple. This is described in the AEBuild document. Briefly, AEBuild is a
tool that allows you to give a detailed Apple Event description with a flexible
syntax. Thus, the above example might be written as:
    aesend NAME misc dosc +---- {“print "Hello World!"”}

The AEBuild syntax allows for more complex descriptions, most importantly lists,
which are required for simple things like 'aevt' 'odoc'.
AEBuild has one major shortcoming. When it performs coercion, it only calls the
coercion handler if the coercion is numeric. For all other coercions, AEBuild simply
modifies the descriptorType field of the AEDesc structure. Because of this, you will
have to use the ability to install coercion handlers to produce HEX data, which you
can place in the AEBuild specification with the aecoerce command. Since the HEX
data is native,  the only coercion requirement is the setting of the descriptorType
field.
If you followed the above discussion, then you will recognize the following
command as a simple request to open a document. You will also note that it
depends upon an external coercion handler named PROC_TEXTalis, which
converts a full path name into an alias.
    aesend TOOL aevt odoc +---- [ concat
        {[ alis(«} [ aecoerce TEXT "Quill.txt" -x alis ] {») ]}
        ]


aeload filename

This command will load all coercion and Apple Event handlers contained in
filename.


aecoerce fromType [-x] data [-x] toType

This command will call the appropriate coercion handler to coerce data from
fromType into toType.
The data is considered to be text, unless the optional -x is present immediately
before the data parameter, in which case it is considered to be hex data. The data
will be read into the dataHandle of an AEDesc structure, then the descriptorType
field set to fromType, and the AEDesc structure passed to AECoerceDesc() to be
coerced into toType.
The resulting data will be returned as text data (which is problematic if it contains
zeros in the data), unless the optional -x is present immediately before thetoType
parameter, in which case the data will be returned as hex data.


aelist

This command will list all open targets that were obtained via aeopen.


aetargets object type zone

This command will list all available targets according to the specified parameters.
The object parameter is the name of a Macintosh in zone. The type field should
usually be set to PPCToolbox.


aeinteract

This command is used when you are running a script via Apple Event, and need
user interaction. If you do not call this, user interaction may behave improperly.


*** APPENDIX  -  A ***

*NOTE*
=============================================================================
I have not done extensive testing of Alpha with XTCLs. However, all those
that I did try worked correctly. For more information on XTCLs, as well as
sample code, download the file XTCL.cpt.bin from the Alpha archive site,
cs.rice.edu in the directory public/Alpha. Additionally, this information
can be obtained with the rest of the tickle distribution from ftp.msen.com
in the directory "pub/vendor/ice".
                                                -- pete
=============================================================================

The tcl external command interface is similar to the HyperCard external
command interface. Your code is a stand alone module that exists as a
resource in the common XTCL File or in a file by itself.

The advantage of having your XTCL in a separate file is the ability to have
access to your own set of resources that are always carried around with the
XTCL. The disadvantage is the cost of opening and close the XTCL's file
every time it is executed. A future release of tickle will cache the current
open XTCL resource, as well as the open resource file, making repeated
calls to the XTCL very fast.

When tickle is asked to execute the external command, it loads the resource
from the (1) application resource fork, (2) the XTCL File resource fork, or (3)
the resource fork of the optional file parameter. The resource is locked
down in memory, and called as a C function. The external command's C
code should begin as:

void
XTCLEntry(argc, argv, xpb)
int            argc;
char            **argv;
XTCLParmBlk        *xpb;

The parameters are similar to what you would expect any C type program
to take, except for the xpb parameter block. This parameter block is your
link back into tickle. Here is the structure:

typedef struct {
 ->    long    version;
<->    long    result;
<->    Handle    resultH;
 ->    short    cmdRefNum;
 ->    Handle    cmdHandle;
 ->    Tcl_Interp    *interp;
 ->    int    (*eval)();
 ->    ModalFilterProcPtr    modalproc;
 -    long    reserved;
    } XTCLParmBlk, *XTCLPBPtr;

The version field is passed in to indicate to the command what level of
functionality the tcl callback function supports, as well as indicate the
version of the parameter block data structure. The current version number
of defined by XTCL_CB_VERSION in the header file XTCL.h and is currently
0x00010001.

The result field is returned by the external command and is to be one of
the predefined constants in XTCL.h. The resultH field contains a handle
that is allocated by tickle, with a length of zero, and passed to the external
command to contain the results of the command. The command will resize
the handle to hold its result, and copy the results into the handle's memory
before returning. The external command should never dispose of the
handle passed in resultH.

The cmdRefNum field is the file system reference number of the file
containing the XTCL command. Remember, this reference number may be
the application's reference number or the number of the XTCL File, if the
command was found in either of these locations. The external command
must never close this file.

The cmdHandle field is the handle to the code resource that contains the
external command itself. It will be locked. Do not unlock, move, modify, or
otherwise mutilate this memory!!!! Consider the handle and data READ
ONLY.

The interp field is a tcl interpreter pointer to the interpreter that called the
external command.

The eval field is a C procedure pointer to the callback routine to evaluate a
tcl statement. It is equivalent to using the eval tcl command. The callback is
used as follows:

   result = (* xpb->eval)(xpb, sHandle, rHandle, stdoutHandle);

Where:
xpb is the parameter block pointer passed to the external command.
sHandle is a handle containing a null terminated string to be evaluated by the tcl
interpreter.
rHandle is a handle for the result of the command. It may be zero length, but if it is
not the results will be placed after the data already in the handle (as determined by
GetHandleSize). The result will not be null terminated, thus, GetHandleSize must
be used to determine the length of the result.
stdoutHandle is a handle for the standard output of the command. This is the
output generated by the print command and error reporting. It may be zero length,
but if it is not the results will be placed after the data already in the handle (as
determined by GetHandleSize). The results will not be null terminated, thus,
GetHandleSize must be used to determine the length of the result. This field may be
NULL.

The modalproc field is a procedure pointer to use in the
ModalFilterProcPointer field of ModalDialog and the like.

The reserved field is reserved.

An external command in MPW C should look like:

#include "xtcl.h"

void
XTCLEntry(argc, argv, xpb)
int            argc;
char        **argv;
XTCLParmBlk    *xpb;
{
char    *ptr, state;
int        i, length, slen;

    xpb->result = TCL_OK;

    length = GetHandleSize(xpb->resultH);

    for (i=1; i < argc; i++)
        slen += strlen(argv[i]) + 1;

    SetHandleSize(xpb->resultH, slen+1);

    state = HGetState(xpb->resultH);
    HLock(xpb->resultH);

    for (ptr=*xpb->resultH, i=1; i < argc; i++) {
        strcat(ptr, argv[i]);
        strcat(ptr, " ");
        ptr += strlen(ptr);
        }

    HSetState(xpb->resultH, state);
    }

And would be linked together with:

XTCL_echo ƒ                ∂
        XTCL_echo.c.o
    Echo '#' Linking XTCL_echo
    Link -t "XTCL" -c "MPS "        ∂
        -rt "XTCL=2020"        ∂
        -sg "echo"            ∂
        -m XTCLEntry            ∂
        -o XTCL_echo            ∂
        XTCL_echo.c.o            ∂
        {CLibraries}StdCLib.o    ∂
        {Libraries}Interface.o

NOTE: The -sg "echo" option in the Link command will determined the
name of the code resource that is produced, and thus the name of the
external command. The -rt "XTCL=2020" option in the Link command
determines the resource type of the code generated, and its resource id.
The resource type must be XTCL, and the resource ID should try to be
unique, but is not critical.

Also remember that stand alone C code must not use global variables, and
must use the -b option when calling the C compiler to use string constants.

Finally, the following code fragment is an example of an XTCL that simply
calls the eval callback routine with its first argument to be evaluated.

#include "xtcl.h"

void
XTCLEntry(argc, argv, xpb)
int        argc;
char        **argv;
XTCLParmBlk    *xpb;
    {
    long        length;
    int        result;
    Handle        rHandle, sHandle;
    char        *script = argv[1];

    xpb->result = TCL_OK;

    length = strlen(script);
    sHandle = NewHandle(length+1);
    rHandle = NewHandle(0);

    if (sHandle != NULL && rHandle != NULL)
        {
        strcpy(*sHandle, script);

        result = (* xpb->eval)(xpb, sHandle, rHandle, NULL);

        length = GetHandleSize(rHandle);
        SetHandleSize(xpb->resultH, length + 1);
        if (MemError() == noErr) {
            memcpy(*xpb->resultH, *rHandle, GetHandleSize(rHandle));
            * (*xpb->resultH + length) = '\0';
            }
        else
            result = TCL_ERROR;

        xpb->result = result;
        }

    if (sHandle != NULL)
        DisposHandle(sHandle);
    if (rHandle != NULL)
        DisposHandle(rHandle);
    }

NOTE: Pascal programmers will need to link with the Pascal glue code to
work. The glue code provides a C entry that will call your Pascal routine for
the XTCL. It also provides glue to callback the interpreter for evaluation.
Please see the example sources and makefile for further details.


*** APPENDIX  -  B ***

The tcl external procedure interface is identical to the interfaces used by the
Apple Event loaders provided with the System Seven Developer CD. These
procedure definitions allow you to define Apple Event Coercion procedures
and Apple Event Handler procedures to be loaded by tickle for use with
tickle's tcl.

The current release of tickle includes two such procedures:
PROC_AEVTtcl1evel and PROC_CSPTTEXTalis. PROC_AEVTtcl1evel  is
an example of an Apple Event Handler that handles the event class tcl1 and
event type eval. PROC_CSPTTEXTalis is an Apple Event Coercion handler
that coerces a full path name passed as data type TEXT into an Alias of type
alis.

To load the external procedure definitions, you must use the aeload
command. The type of handler and its input and output data types are
determined by the name of the code resource. The first four characters are
the handler type:

    AEVT    - Apple Event Handler.
    CSPT    - Data Pointer based Coercion Routine.
    CSDS    - Data Descriptor based Coercion Routine.

The second four characters determine for each handler:

    AEVT    - Apple Event Handler Event Class.
    CSPT    - Coercion input data type.
    CSDS    - Coercion input data type.

The third four characters determine for each handler:

    AEVT    - Apple Event Handler Event Type.
    CSPT    - Coercion output data type.
    CSDS    - Coercion output data type.

The procedures are simply Pascal code resources that are declared exactly
as they are defined in IM Volume VI.

    AEVT    - Apple Event Handler:

        pascal OSErr
        PROCEntry(message, reply, refcon)
        AppleEvent        *message;
        AppleEvent        *reply;
        long            refcon;


CSPT    - Pointer based Coercion Handler:

        pascal OSErr
        PROCEntry(dataType, dataPtr, dataSize, toType, refCon, resultDesc)
        DescType        dataType;
        char        *dataPtr;
        long        dataSize;
        DescType        toType;
        long        refCon;
        AEDesc        *resultDesc;

    CSPT    - Pointer based Coercion Handler:

        pascal OSErr
        PROCEntry(dataType, dataPtr, dataSize, toType, refCon, resultDesc)
        DescType        dataType;
        char        *dataPtr;
        long        dataSize;
        DescType        toType;
        long        refCon;
        AEDesc        *resultDesc;

The refCon field passed to the procedures defined for Apple Event and
Coercion contains a pointer to a parameter block that allows the procedures
to make calls back to the tcl interpreter. You obtain the pointer to this
paramater block as follows:

    XPROCPBPtr    cbpb;

        cbpb = (XPROCPBPtr) refcon;

    typedef struct {
        long        version;    /* Version of the Cmd interface. */
        Tcl_Interp    *interp;    /* Interpreter calling this XTCL. */
        int        (*eval)();    /* Callback procedure (C) for tcl
                           script evaluation */
        DescType    reserved1;    /* reserved */
        DescType    reserved2;    /* reserved */
        long        reserved3;    /* reserved */
        } XPROCParmBlk, *XPROCPBPtr;

The version field is passed in to indicate to the command what level of
functionality the tcl callback function supports, as well as indicate the
version of the parameter block data structure. The current version number
of defined by XPROC_CB_VERSION in the header file XTCL.h and is currently
0x00010001.

The interp field is a tcl interpreter pointer to the interpreter that called the
external command.

The eval field is a C procedure pointer to the callback routine to evaluate a
tcl statement. It is equivalent to using the eval tcl command. The callback is
used as follows:

result = (* xpb->eval)(xpb, sHandle, rHandle, stdoutHandle);
Where:
xpb is the parameter block pointer passed to the external command.
sHandle is a handle containing a null terminated string to be evaluated by the tcl
interpreter.
rHandle is a handle for the result of the command. It may be zero length, but if it is
not the results will be placed after the data already in the handle (as determined by
GetHandleSize). The result will not be null terminated, thus, GetHandleSize must
be used to determine the length of the result.
stdoutHandle is a handle for the standard output of the command. This is the
output generated by the print command and error reporting. It may be zero length,
but if it is not the results will be placed after the data already in the handle (as
determined by GetHandleSize). The results will not be null terminated, thus,
GetHandleSize must be used to determine the length of the result. This field may be
NULL.

The reserved1 field is reserved.

The reserved2 field is reserved.

The reserved3 field is reserved.